Editorial review: Document popover="hint" #37990

chrisdavidmills · 2025-02-06T16:59:53Z

Description

Chrome 133 supports the popover attribute hint value, which creates popovers that do not light-dismiss auto popovers when shown. This is useful for situations where, for example, you have toolbar buttons that can be pressed to show UI popovers, but you also want to reveal tooltips when the buttons are hovered, without dismissing the UI popovers.

This PR adds the HTML popover attribute hint value to the popover HTML global attribute page and the HTMLElement.popover DOM API equivalent.

It also adds a section explaining how to use popover="hint" to the Popover API "Using..." guide.

As a bonus, I've also added info about the implicit anchor references that are created between popovers (makes CSS anchor positioning easier to use with popovers).

See https://chromestatus.com/feature/5073251081912320 for the data source.

There is no reason why this can't be tech-reviewed now, but we can't merge it until the dom-examples example is reviewed and merged. I am therefore keeping this as a draft for now.

Motivation

Additional details

Related issues and pull requests

BCD: Chrome 133 supports HTML popover="hint" attribute value browser-compat-data#25864
dom-examples example addition: Add popover=hint example dom-examples#295
Add documentation of new dialog light dismiss behaviors #37196

Fixes mdn/mdn#598
Fixes #38233

github-actions · 2025-02-06T17:01:17Z

Preview URLs (16 pages)

Flaws (82)

Note! 7 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Popover_API/Using
Title: Using the Popover API
Flaw count: 8

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/inset_properties is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/API/HTMLElement
Title: HTMLElement
Flaw count: 5

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
- Can't resolve /en-US/docs/Web/API/HTMLElement/cancel_event

URL: /en-US/docs/Web/API/HTMLElement/showPopover
Title: HTMLElement: showPopover() method
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/HTML/Element/input
Title: <input>: The HTML Input element
Flaw count: 46

broken_links:
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Web/API/validityState/rangeOverflow is ill cased
- /en-US/docs/Web/API/validityState/tooLong is ill cased
- and 18 more flaws omitted
macros:
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Web/API/validityState/rangeOverflow which is a redirect
- Macro produces link /en-US/docs/Web/API/validityState/tooLong which is a redirect
- and 18 more flaws omitted

URL: /en-US/docs/Web/HTML/Element/button
Title: <button>: The Button element
Flaw count: 4

broken_links:
- /en-US/docs/Glossary/user_agent is ill cased
- /en-US/docs/Glossary/accessible_name is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
- Macro produces link /en-US/docs/Glossary/accessible_name which is a redirect

URL: /en-US/docs/Web/HTML/Global_attributes/popover
Title: popover
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/top_layer is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/CSS/anchor-name
Title: anchor-name
Flaw count: 7

broken_links:
- /en-US/docs/Glossary/inset_properties is ill cased
- /en-US/docs/Web/CSS/Value_definition_syntax#single_bar is a redirect
- /en-US/docs/Web/CSS/Value_definition_syntax#hash_mark is a redirect
macros:
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
- Macro produces link /en-US/docs/Web/CSS/initial_value which is a redirect
- Macro produces link /en-US/docs/Web/CSS/inheritance which is a redirect
- Macro produces link /en-US/docs/Web/CSS/computed_value which is a redirect

URL: /en-US/docs/Web/CSS/CSS_anchor_positioning/Using
Title: Using CSS anchor positioning
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/inset_properties is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect

URL: /en-US/docs/Web/CSS/position-anchor
Title: position-anchor
Flaw count: 6

broken_links:
- /en-US/docs/Glossary/inset_properties is ill cased
- /en-US/docs/Web/CSS/Value_definition_syntax#single_bar is a redirect
macros:
- Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
- Macro produces link /en-US/docs/Web/CSS/initial_value which is a redirect
- Macro produces link /en-US/docs/Web/CSS/inheritance which is a redirect
- Macro produces link /en-US/docs/Web/CSS/computed_value which is a redirect

External URLs (3)

URL: /en-US/docs/Web/API/Popover_API/Using
Title: Using the Popover API

https://mdn.github.io/dom-examples/popover-api/popover-hint/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLElement/anchorElement
Title: HTMLElement: anchorElement property

https://github.com/whatwg/html/pull/9144 (1 time)

URL: /en-US/docs/Web/HTML/Global_attributes/anchor
Title: anchor

https://github.com/whatwg/html/pull/9144 (1 time)

(comment last updated: 2025-02-21 08:49:33)

mfreed7

LGTM! Just a few small comments.

files/en-us/web/api/htmlelement/popover/index.md

files/en-us/web/api/popover_api/using/index.md

files/en-us/web/html/global_attributes/popover/index.md

files/en-us/web/api/htmlelement/popover/index.md

files/en-us/web/api/popover_api/using/index.md

files/en-us/web/api/htmlelement/popover/index.md

files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md

files/en-us/web/api/htmlelement/showpopover/index.md

hamishwillee · 2025-02-14T00:15:31Z

files/en-us/web/api/htmlelement/togglepopover/index.md

+    - `source` {{optional_inline}}
+      - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, the control button or link associated with the popover.
+
+Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.


See https://github.com/mdn/content/pull/37990/files#r1955372659

@chrisdavidmills I'm closing all these, but once you've looked at https://github.com/mdn/content/pull/37990/files#r1958808280 you might want to link these to a fixed up section in the Using doc as an intermediate step to getting to the CSS anchor positioning doc.

I.e. "Associating anchor and positioned elements for more details on anchor references." is very general, whereas a specific example for popover hints would be very specific and make things a lot easier

Right, in my next commit, I have updated all of these bits to briefly explain all of the useful additional effects, and link to the relevant sections in the "Using..." guides. I don't want to repeat the entire explanation on each page.

files/en-us/web/api/htmlinputelement/popovertargetelement/index.md

files/en-us/web/api/popover_api/using/index.md

Co-authored-by: Hamish Willee <[email protected]>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

files/en-us/web/api/htmlelement/popover/index.md

yisibl · 2025-02-17T05:16:40Z

We should probably add some indication that Interest Invokers can be used in the future to make it trigger via hover.

https://open-ui.org/components/interest-invokers.explainer

mfreed7 · 2025-02-18T16:00:15Z

We should probably add some indication that Interest Invokers can be used in the future to make it trigger via hover.

https://open-ui.org/components/interest-invokers.explainer

I think MDN's policy is to only document things that are available in the platform, not future stuff. But I'm not positive about that.

chrisdavidmills · 2025-02-19T10:40:59Z

We should probably add some indication that Interest Invokers can be used in the future to make it trigger via hover.
https://open-ui.org/components/interest-invokers.explainer

I think MDN's policy is to only document things that are available in the platform, not future stuff. But I'm not positive about that.

That's correct. I'm aware of the interest invokers stuff, but we should save it for a separate PR, when it is implemented.

files/en-us/web/api/htmlelement/showpopover/index.md

files/en-us/web/api/htmlelement/togglepopover/index.md

files/en-us/web/api/popover_api/using/index.md

lukewarlow · 2025-02-19T11:14:45Z

files/en-us/web/css/css_anchor_positioning/using/index.md

@@ -29,9 +29,9 @@ Historically, associating an element with another element and dynamically changi

 ## Associating anchor and positioned elements

-To associate an element with an anchor, you need to first declare which element is the anchor, and then specify which positioned element(s) to associate with that anchor. This can be done via CSS or via the HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute.
+To associate an element with an anchor, you need to first declare which element is the anchor, and then specify which positioned element(s) to associate with that anchor. This creates an anchor reference between the two. This association can be created explicitly via CSS or via the HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute, or in some cases, implicitly.


For a follow-up: Do we still want to document the anchor attribute? It's not shipped in any browsers and afaik doesn't seem like it will soon because the wider whatwg/csswg aren't convinced by it. This is partly what lead to popovertarget (and commandfor pointing at a popover) creating an implicit anchor relationship.

We ended up documenting the anchor attribute very early on because it was available in Canary and seemed to be a goer. If it looks like it will be killed off, I am happy to remove it. Maybe file an issue about it and wait for more definite action either way?

Ha h! I just commented on this pointing to you @chrisdavidmills . Josh's summation there is correct - the reference is OK because it accurately reflects the situation, but the guide should remove the discussion around use of the anchor until this is either removed or released (not in canary).

Done in b9c9e03

files/en-us/web/html/global_attributes/popover/index.md

…o popover=hint

lukewarlow

Non-authoritative LGTM

hamishwillee · 2025-02-21T05:34:22Z

files/en-us/web/api/popover_api/using/index.md

@@ -341,11 +355,31 @@ See our [Popover blur background example](https://mdn.github.io/dom-examples/pop

 ### Implicit popover anchor associations


FWIW I still think I'm more likely to find this topic if you call it "Positioning a popover" or "Position a popover relative to its invoker". This heading only means something to me because I already understand it.

I'm going to push back on this. I don't think changing the heading to something like this would make it particularly easier to find the section, and it would also be kind of inaccurate as to the focus of the section. It's not about positioning the popovers; that's covered in the previous section. This section is specifically about the fact that you don't need to include the anchor position association CSS features the elements in question are popovers.

As a compromise, I have promoted it to an h2, to make it more visible on the actual page.

hamishwillee · 2025-02-21T05:35:06Z

files/en-us/web/api/popover_api/using/index.md

@@ -341,11 +355,31 @@ See our [Popover blur background example](https://mdn.github.io/dom-examples/pop

 ### Implicit popover anchor associations

-Associating a popover with a control using the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) and [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attributes creates an implicit anchor reference between the two, as does programmatically associating a popover action such as {{domxref("HTMLElement.showPopover", "showPopover()")}} with a control using the `source` option. See [Associating anchor and positioned elements](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using#associating_anchor_and_positioned_elements) for more details on anchor references.
+Associating a popover with its invoker using the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute or the `source` option of the {{domxref("HTMLElement.showPopover()")}} or {{domxref("HTMLElement.togglePopover()")}} methods creates an implicit anchor reference between the two.


Might be worth spelling out that this works for both hints and autos.

PS I very much like this update. I hope you agree it was worth the effort :-)

Might be worth spelling out that this works for both hints and autos.

It works for manual popovers too. I've clarified this by changing the first line to "Associating any kind of popover..."

PS I very much like this update. I hope you agree it was worth the effort :-)

Indeed, I do ;-)

Document popover=hint

7363db0

chrisdavidmills requested review from a team as code owners February 6, 2025 16:59

chrisdavidmills requested review from estelle and wbamberg and removed request for a team February 6, 2025 16:59

chrisdavidmills marked this pull request as draft February 6, 2025 17:00

github-actions bot added Content:HTML Hypertext Markup Language docs Content:WebAPI Web API docs labels Feb 6, 2025

chrisdavidmills changed the title ~~Document popover=hint~~ Technical review: Document popover="hint" Feb 6, 2025

github-actions bot added the size/m [PR only] 51-500 LoC changed label Feb 6, 2025

mfreed7 reviewed Feb 11, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

files/en-us/web/api/popover_api/using/index.md Outdated Show resolved Hide resolved

files/en-us/web/html/global_attributes/popover/index.md Outdated Show resolved Hide resolved

Fixes for mfreed7 comments, added info about implicit anchor references

c7749da

github-actions bot added the Content:CSS Cascading Style Sheets docs label Feb 12, 2025

chrisdavidmills marked this pull request as ready for review February 12, 2025 15:07

chrisdavidmills requested a review from a team as a code owner February 12, 2025 15:07

chrisdavidmills requested a review from mfreed7 February 12, 2025 15:08

chrisdavidmills changed the title ~~Technical review: Document popover="hint"~~ Editorial review: Document popover="hint" Feb 12, 2025

chrisdavidmills mentioned this pull request Feb 13, 2025

Chromium 133 support for source property and implicit anchor references mdn/browser-compat-data#25909

Merged

hamishwillee reviewed Feb 13, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 13, 2025

View reviewed changes

files/en-us/web/api/popover_api/using/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 13, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 13, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 14, 2025

View reviewed changes

files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 14, 2025

View reviewed changes

files/en-us/web/api/htmlelement/showpopover/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 14, 2025

View reviewed changes

files/en-us/web/api/htmlinputelement/popovertargetelement/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 14, 2025

View reviewed changes

files/en-us/web/api/popover_api/using/index.md Outdated Show resolved Hide resolved

chrisdavidmills and others added 3 commits February 14, 2025 12:32

Update files/en-us/web/api/htmlelement/popover/index.md

ca545ad

Co-authored-by: Hamish Willee <[email protected]>

Update files/en-us/web/html/global_attributes/popover/index.md

fb17a7c

Co-authored-by: Hamish Willee <[email protected]>

Update files/en-us/web/api/htmlelement/popover/index.md

7564a0b

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions bot reviewed Feb 14, 2025

View reviewed changes

files/en-us/web/api/htmlelement/popover/index.md Outdated Show resolved Hide resolved

Fixes for hamishwillee review comments

49d5cd0

chrisdavidmills requested a review from hamishwillee February 14, 2025 15:32

chrisdavidmills mentioned this pull request Feb 19, 2025

Add imperative invoker updates to popover API #37133

Closed

Merge branch 'main' into popover=hint

231d6e9